SPEC-UX-TKT · v1.0
29 June 2026
Owner: Platform team

Design specification · build-ready · Support · Tickets

The ticket communication system — one support conversation, three apps

The exhaustive design specification for RiverSync's multi-party support conversation: the surface a customer uses to talk to the RiverSync service desk, the agent uses to work every tenant's tickets, and a servicing partner uses once they are brought onto a unit. It is specified as one reusable component — the same layout, command bar, thread and composer, reskinned per app by a single viewer setting — so Portal, Admin and Partners never diverge. Written so an implementer needs no further decisions: each region, state, class, icon and viewer rule is named.

1What it is — and what it is not

The ticket communication system is a multi-party support conversation about one device. The customer opens a ticket (often from an alarm) and talks to the RiverSync service desk first line; RiverSync brings a servicing partner onto the thread when a unit's maintenance agreement makes them relevant. Every party works the same conversation — only what they may see and do changes.

2The shape at a glance

One immersive page: a full-width context-aware command bar, then a list → thread → context-rail body that fills the height. The conversation parties are always customer + RiverSync, plus a partner once brought in. The surface is identical across the three apps; the differences are entirely captured by viewer.

The five W's of every ticket are visible in the list row before it is opened — who (the other parties' avatars + names), about what (subject + category), which device (id + status dot), when (last activity), what state (status badge + unread dot).

3One surface, three viewers

The component takes a single viewer prop. Everything app-specific — the shell chrome (App pill, nav, tenant), which parties are shown as "the others", the composer affordances and what is hidden — derives from it. There is no forked code per app, and no in-app "view as" switcher — each app deploys its own viewer-locked page through the shared mounter, so a customer only ever sees the customer view (in the Portal app), an agent the agent view (in Admin), a partner the partner view (in Partners).

viewer	App / pill	Signed-in party	What this viewer can do
customer	Portal · --portal	Customer (Sanyodenki)	Open tickets from an alarm/device, reply to RiverSync (and the partner once present), request a partner on site, mark resolved. Never sees internal notes.
agent	Admin · --admin	RiverSync service desk	Works every tenant's tickets. Reply / internal note toggle, quick replies, bring in a servicing partner, schedule a visit, resolve/reopen. Sees everything.
partner	Partners · --partners	Servicing partner (Nera)	Sees only tickets they have been brought onto, scoped to their devices. Replies to RiverSync & the customer. Never sees RiverSync internal notes.

3.1Bringing a partner in

A ticket starts as customer↔RiverSync. RiverSync (or, on request, the customer) brings a servicing partner onto the thread when the device's active maintenance agreement names one. This is a first-class event, not a re-route.

4The data the surface renders

The UI never invents fields. Every rendered value maps to the ServiceTicket + TicketMessage model owned by the Support domain and defined in SPEC-ERD-PTL. Field names below are the presentation contract the prototype reads.

5Layout & grid

Below the shell chrome the page is a vertical stack: a full-width command bar, then a body grid that fills the remaining height — a fixed conversation list, the thread, and an optional context rail. Each column scrolls independently; the page itself does not scroll.

	Region	Sizing	Specification
1	Command bar .pv-cmdbar	full width · 40px	Fixed at the top — the one chrome that never scrolls (height 40px, matching the shell top bar). Left: identity tile (Tickets + open-count + viewer label). Middle: context commands (hairline-divided). Right: search + primary Reply.
2	List column .pv-tk__list	340px	Tools row (filter segment + count) pinned over an independently scrolling stack of ticket rows — the scrollbar is hidden (scrollbar-width:none) for a clean rail.
3	Category chip .pv-tkcat	auto	The ticket's category (incident / maintenance / firmware / question) with icon + tone, atop the subject.
4	Participant strip .pv-tkparty	auto	The other parties as avatar pills with presence; a dashed Bring in / Request partner chip when none.
5	Detail scroll .pv-tkscroll	fills · scrolls	The center scrolls as one region — the ticket header scrolls with the thread (only the command bar and composer stay fixed). Holds the header then the ChatThread (messages ascending; mine right, others left; cards under bubbles; day / event / unread / typing rows). Auto-scrolls to newest on open & send.
6	Composer .pv-tkcomp	auto · pinned	Control row (mode toggle / visibility + quick replies) over the DS ChatComposer; locked note when resolved.
7	Context rail .pv-tk__rail	300px / 40px	Two states, toggled from the rail. Details (full — device, maintenance agreement, participants, origin) at 300px; and a minimized icon-rail glance at 40px — the collapsed left-sidebar width. At 40px every fact becomes one icon with a hover tooltip and tap-to-act: a tinted status glyph, a priority dot, the device, SLA, the agreement tier+partner, the origin alarm, then the participant avatars stacked. State persists in localStorage. Hidden under 1180px and in split layout.

Grid: .pv-tk{display:grid; grid-template-columns:340px 1fr;}; .pv-tk--rail{…340px 1fr 300px;}. The page is immersive (.pv-tkpage--immersive): no page padding, fills below the 40px top bar. The center column is a single scroller (.pv-tkscroll) carrying header + thread; the command bar (40px) and composer are the only fixed chrome. Under 900px the list collapses and the thread takes over (master-detail) — see §11 responsive.

6The command bar

Adapted from the pipeline communications navbar: a full-width, square, hairline-divided strip of commands. It is context-aware — the commands depend on the selected ticket, its status and the viewer. The primary action sits at the right with search; when nothing is selected the middle shows the hint "Select a ticket to act on it."

Command	Icon · style	Shown for	Behavior
Device	server	all	Opens the linked device. Label is the device id (e.g. MDC-2044).
Bring in partner	hub	agent · no partner	Resolves & sets the servicing partner; writes the bring-in event (V-1).
Request partner	hub	customer · no partner	Raises a request to RiverSync (toast) (V-2).
Schedule visit	calendar	agent · open	Opens the slot proposer for the servicing partner.
Resolve	success · ok	all · open	Sets status=resolved; writes a resolve event; locks the composer.
Reopen	refresh	all · resolved	Sets status=open; writes a reopen event; unlocks the composer.
Mark unread	email · icon	all	Re-flags the selected ticket unread without leaving it.
Reply	corner-down-left · primary	all · open	Right edge. Focuses the composer textarea. No toast.

6.1The list & row

The left column is a pinned tools row (the Open / All / Resolved segment + an N shown count) over scrolling rows. One row is selected at a time and reflected in the thread.

Element	Spec
Party avatars	Up to two overlapping 30px rs-av tiles — the other parties (presence dot when online). Two-initial, DS palette (rs-av-c0…c5).
Who + time	Top line: the other parties' short names joined by ·; a paperclip when the thread has attachments; relative time.
Subject + preview	Two-line subject (bold when unread) + one-line preview of the latest message.
Foot	Mono ticket id · device id with a status dot · the status badge (DS Badge, right-aligned).
Unread · selected	is-unread → accent dot + bold subject; is-active → accent-soft fill + 3px left bar. Selecting clears unread.

7The thread & its parties

The reader is a single scrolling region: a header that scrolls away with the conversation — a compact, horizontal two-row composition (row 1: category · subject · id/opened/SLA on the left, status & priority badges + actions on the right; row 2: the participant strip and the linked-context chips side by side) — then the thread. Only the command bar and the composer stay fixed. The thread is the DS ChatThread; messages map to its items.

Region	Specification
Header sub-line	Status badge + priority badge + mono id + opened date + SLA (clock) — the facts of the ticket.
Participant strip .pv-tkparty	One pill per other party: 26px avatar (presence dot), short org name + role line ("Service desk · first line" / "Servicing partner" / "Customer", with · online when present). RiverSync's pill carries the accent tint.
Linked chips .pv-tklinks	Linked + a chip per related record: Device (always), Alarm (when from an alert, danger tone), Gold/Silver agreement (maintenance tone) → the partner. Each deep-links.
Message bubble	Mine = right (accent-soft), others = left (--surface-2). Avatar + name (others carry · {org}) + time; markdown body; cards beneath.
Cards under a bubble	ChatAlertCard (device alert/alarm) · ImageSet / FileAttachment · ArtifactCard (shared .md) · SlotPicker → AppointmentCard (visit).
System rows	day divider · event row (ticket opened / resolved / partner brought in) · unread marker.

7.1Avatars — the pipeline idiom

Avatars are the two-initial rs-av tiles from the communications system (square 2px, DS palette rs-av-c0…c5), sized via --s: 30px in list rows (overlapping −10px with a surface ring), 26px in the strip, 28px in the rail, sm in bubbles. Presence is the DS corner dot (rs-av__status online). This replaces the former single-letter circular avatar so every surface — list, strip, bubble, rail — reads identically and matches Pipeline.

8Communicating in the chat area

The composer is the one entry point, and it adapts to the viewer. Around the DS ChatComposer (autosizing textarea, attach with progress, drag-and-drop, markdown preview, Enter-to-send) sits a control row that carries the operational affordances.

Capability	Viewer	Specification
Reply vs internal note	agent	A segmented toggle Reply · Internal note. In note mode the placeholder, the visibility line and the sent bubble all switch — the message is stored Note=true and never shown to customer/partner (§4 Note rule). A live visibility line states exactly who can see the next message.
Quick replies (canned)	agent	A Quick replies popover of curated, sentence-case presets (Acknowledge · Ask for a reading · Dispatching a partner · Confirm before close). Picking one sends it immediately as a normal reply.
Attachments	all	Files & pictures stage with progress chips (drag-and-drop supported); each posts as a FileAttachment / ImageSet card under the bubble. Images open a lightbox.
Device alert / alarm cards	all	A ticket opened from an alarm carries the ChatAlertCard inline (severity tone, alarm ping) with a View deep-link to the alert.
Visit scheduling	agent	The composer's calendar tool (reply mode only) proposes visit slots (SlotPicker); a confirmed visit renders an AppointmentCard in-thread.
Visibility line	customer · partner	Above the composer: "Visible to {parties}" — so a sender always knows the audience. Resolved tickets show the locked note instead.

8.1Presence & typing

Two live signals keep the conversation feeling staffed.

9Interactions & states

Every status change and message write runs the same way regardless of which control fired it (command bar, header menu or composer), so behavior is identical across the surface.

Action	Result	Toast
Reply	Append message; (reply mode) trigger typing	— (no toast)
Internal note	Append Note=true message (agent)	— (no toast)
Quick reply	Send the chosen preset immediately	— (no toast)
Resolve	status=resolved; resolve event; lock composer	"Ticket resolved · TKT status set to Resolved." (success)
Reopen	status=open; reopen event; unlock	"Ticket reopened…" (info)
Bring in partner	Set partner; bring-in event	"Partner brought in · {Partner} added to this ticket." (info)
Mark unread	Re-flag the ticket unread	"Marked unread…" (info)

9.1Resolved & locked

A resolved ticket replaces the composer with a locked note — "This ticket is resolved. Reopen it to keep talking." The command bar swaps Resolve for Reopen and drops the primary Reply. Reopening restores the open state and the composer.

9.2Empty & no-match

No selection → the thread shows .pv-tk__empty (ticket icon, "Select a ticket"). A filter that matches nothing → .pv-tkrow__none (inbox icon, "No tickets in this view."). Layout reserves its dimensions; the surface never reflows on data arrival (mirrors the charts rule).

9.3Read receipts

Delivery state advances sendingsentdeliveredread with the DS tick (single → double → accent double). Receipts are derived, not hand-set: one of my messages reads as read once any later message from another party exists; the newest unanswered one shows delivered. Receipts show only on my own outgoing messages — never on incoming. A failed send shows a danger state with Retry; it never silently disappears.

10Design-system mapping

Every element resolves to a RiverSync DS v2 component, class, icon or token. The surface is a React page composing the DS chat layer; the pv-tk* / pv-cmdbar* classes are the Portal-local layer in portal.css, themed entirely through DS tokens.

Element	Class / component	DS basis
App pill (top bar)	rs-portalbadge--portal / --admin / --partners	Canonical app badge per viewer (shell-chrome.css). Mandatory.
Shell	AppShell (hub / admin) · vanilla shell (partners)	The DS shell; the partner pill is re-tinted where AppShell ships no partners config (see §10.1).
Thread	ChatThread + ChatMessage / ChatEvent / ChatDay / ChatUnread / ChatTyping	DS chat system — bubbles, delivery ticks, typing dots.
Composer	ChatComposer	DS composer — attach + progress, drag-drop, markdown, schedule hook.
Cards	ChatAlertCard · FileAttachment · ImageSet · ArtifactCard · SlotPicker · AppointmentCard	DS card-under-bubble idiom.
Avatar	rs-av rs-av-c0…c5 + rs-av__status	DS avatar tile (square, two-initial) + presence dot.
Status / priority	Badge (tone)	DS status badge — 2px radius, soft tint, sentence case.
Command buttons	pv-cmd pv-cmd--primary / --ok / --icon	Command-bar buttons over DS tokens (the pipeline pl-cmd idiom).
Segments	rs-seg rs-seg--sm	DS segmented control (filter + reply/note toggle).
Toast	PVToast(title, msg, kind)	Portal toast — success / info / warning.
Icons	<Icon name="…"/>	Proprietary icon system (the G geometry table) — never a third-party set.

Icons in use: ticket · server · hub · calendar · success · refresh · email · corner-down-left · search · alert · wrench · chevron-right · more-horizontal · paperclip · image · file-text · chat · lock · eye · check · plus · inbox · clock. Any new glyph is added to the DS G table first, never drawn inline.

10.1The partners-badge note

11Reuse rules & responsive

The whole point of this spec is one surface, embedded by every app. These rules keep it that way.

11.1Responsive

Breakpoint	Behavior
> 1180px	Full three-column (list · thread · rail) in rail layout; the rail toggles between full Details (300px) and a minimized icon-rail glance at 40px — the collapsed left-sidebar width — every fact an icon + tooltip (persisted).
≤ 1180px	Rail hidden; list + thread.
≤ 1024px	Command-bar identity sub-label + search hide; commands stay.
≤ 900px	Command labels collapse to icons; list collapses, thread takes over (master-detail).

11.2Accessibility, keyboard & motion

Concern	Requirement
Semantics	List rows are buttons (selected reflected); the thread is a labelled log; the unread dot and presence dot carry text equivalents; status/priority are badge text, not color-only.
Focus	3px soft ring (--ring) on :focus-visible; Reply moves focus to the composer textarea; menus close on outside-click / Escape.
Color	Category, status, priority and note all pair an icon or text with their tint — never color alone.
Motion	Typing dots and delivery ticks honor prefers-reduced-motion; no decorative looping.
Hit targets	Rows ≥ 38px; command/icon buttons ≥ 40px; composer Send comfortably tappable.

12As-built vs production targets

The prototype is the source of truth for look & behavior; these are the deltas a production build must close. None changes the model.

Area	As-built	Production target
Partner shell	re-tinted pill	First-class partners portal in AppShell (§10.1).
Typing & presence	simulated	Live presence + typing over the realtime hub.
Read receipts	derived from thread	Real per-message delivery/read receipts pushed from the server.
Send / status	local state	Persist TicketMessage / status, write events, emit domain events.
Quick replies	fixed presets	Editable canned-reply library, per-agent & per-team.
Attachments	placeholder cards	Real upload + image lightbox + file download.
Scheduling	toast / cards	Live slot proposal → partner confirm → calendar write.

13Open questions & proposed requirements

• Formalize the shared surface. PTL-4 owns the customer view; the agent (Admin) and partner (Partners) reuse is, today, implied. Proposed: a platform requirement (or paired PAR-/ADM- lines) naming the one reusable ticket-communication surface across the three apps — logged here pending the PRD/ERD cascade.
• Internal-note authoring. Confirm only RiverSync may author notes (not partners) and whether a partner may have a partner-only note lane.
• Partner scope. Is a partner scoped to tickets where they are the current servicing partner only, or also historical ones on devices they once covered?
• Channels. Do tickets stay in-app only, or (like Pipeline) accept email/LINE replies threaded back in? If so, channel chips join the message meta.
• Presence source. Confirm the realtime presence/typing transport (the Pipeline inbox proposes a SignalR hub; tickets would share the pattern).

14Traceability

This spec	Traces to
Whole document	PTL-4 (Portal PRD) — tickets as a multi-party support conversation; reused by SPEC-APP-PAR · SPEC-APP-ADM.
Data model (§4)	ServiceTicket · TicketMessage (SPEC-ERD-PTL), Support domain (SPEC-DDD-SUP).
Bring-in & agreements (§3.1)	Maintenance agreement & partner scope (SPEC-PRD-MNT, SPEC-ERD-PAR).
Process (§9)	SPEC-PWF-INC · ticket lifecycle in SPEC-DWF-SUP.
Notes / visibility (§4, §8)	Federation roles & tenant visibility (SPEC-PRD-FED).

15Revision history

Version	Date	Changes
1.0	29 Jun 2026	First issue — the ticket communication system specified as one reusable surface deployed as a dedicated, viewer-locked page inside each app (no "view as" switcher): Portal (customer) · Admin (RiverSync agent) · Partners (servicing partner). Scope & distinctions (§1–2), the three viewers & partner bring-in (§3), the ServiceTicket/TicketMessage data (§4), layout & grid with annotated wireframe (§5), the context-aware command bar + list/row (§6), thread, parties & the pipeline avatar idiom (§7), communicating in the chat — internal notes, quick replies, attachments, alert cards, scheduling, presence & typing (§8), interactions/states & read receipts (§9), design-system mapping incl. the partners-badge note (§10), reuse rules & responsive (§11), as-built vs target, open questions / proposed requirements, traceability (§12–14). Brought the avatar design and the command-bar navigation from the Pipeline communications system into the ticket surface, and corrected the shared shell brand to the real RiverSync logo/mark vectors. A presentation view over a settled model — no new entities, fields, events or rules; proposed reuse requirement logged. Added to the Design specs family (SPEC-UX-TKT).